/**
 * <p>Represents the root of an Atom Publishing Protocol Introspection Document.</p>
 * 
 * <p>Per APP Draft-08:</p>
 * 
 * <pre>
 *  The root of an introspection document is the "app:service" element.
 *
 *  The "app:service" element is the container for introspection
 *  information associated with one or more workspaces.  An app:service
 *  element MUST contain one or more app:workspace elements.
 *  
 *  appService =
 *     element app:service {
 *        appCommonAttributes,
 *       ( appWorkspace+
 *          &amp; extensionElement* )
 *     }
 * </pre>
 */
public interface Service extends ExtensibleElement {

  /**
   * Return the complete set of workspaces
   * @return A listing of app:workspaces elements
   */
  List<Workspace> getWorkspaces();
  
  /**
   * Return the named workspace
   * @param title The workspace title
   * @return A matching app:workspace
   */
  Workspace getWorkspace(String title);
  
  /**
   * Add an individual workspace
   * @param workspace a app:workspace element
   */
  Service addWorkspace(Workspace workspace);

  /**
   * Add an individual workspace
   * @param title The workspace title
   * @return The newly created app:workspace
   */
  Workspace addWorkspace(String title);
  
  /**
   * Returns the named collection
   * @param workspace The workspace title
   * @param collection The collection title
   * @return A matching app:collection element
   */
  Collection getCollection(String workspace, String collection);
  
  /**
   * Returns a collection that accepts the specified media types
   * @param a listing of media types the collection must accept
   * @return A matching app:collection element
   */
  Collection getCollectionThatAccepts(Activation.MimeType[] types);
  
  /**
   * Returns a collection that accepts the specified media types
   * @param a listing of media types the collection must accept
   * @return A matching app:collection element
   */
  Collection getCollectionThatAccepts(String[] types);
  
  
  /**
   * Returns collections that accept the specified media types
   * @param a listing of media types the collection must accept
   * @return A listing matching app:collection elements
   */
  List<Collection> getCollectionsThatAccept(Activation.MimeType[] types);
  
  /**
   * Returns collections that accept the specified media types
   * @param a listing of media types the collection must accept
   * @return A listing of matching app:collection elements
   */
  List<Collection> getCollectionsThatAccept(String[] type);
  
}

